home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d3 / mcroade3.arc / MCOMPILE.DOC < prev    next >
Text File  |  1991-07-06  |  12KB  |  262 lines
  1.                            MCompile.exe
  2.               A Utility for Compiling ASCII Text File
  3.                 Listings of WordPerfect 5.1 Macros
  4.                 into Executable Macro (.wpm) Files
  5.  
  6.                                 by
  7.  
  8.                       Jeffrey S. Kane, Ph.D.
  9.                 Performance Sciences International
  10.                           Summerfield, NC
  11.  
  12. 1.   Read the MacroAde.doc and Disclaim.er files distributed with this
  13.      utility.
  14.  
  15. 2.   Requires:
  16.      
  17.      A.   WordPerfect 5.1 (for use of compiled macros)
  18.  
  19.      B.   MS/PC-DOS 3.0 or higher
  20.  
  21.      C.   An ASCII source file that conforms to the compiler's
  22.           structure and syntax specifications.
  23.  
  24. 3.   Features:
  25.  
  26.      A.   Fast    (e.g., less than 4 seconds for a 10K source file
  27.           on 386DX-20 machine).
  28.  
  29.  
  30.      B.   Compact .exe file size (9193 bytes)
  31.  
  32.      C.   Accurate
  33.  
  34.      D.   Powerful: accepts source files of unlimited size.
  35.  
  36.      E.   Handles either spaces or tabs as formatting characters
  37.           at the beginnings of lines (up to first significant
  38.           character on any line).
  39.  
  40.  
  41. 4.   Installation:
  42.  
  43.      No installation is required other than to copy the
  44.      MCompile.exe file to the directory where your WordPerfect
  45.      macros reside.  As in the case of Macrolst, we recommend
  46.      locating MCompile in this directory for the sake of
  47.      convenience, there being no inherent technical requirement to
  48.      do so.
  49.  
  50. 5.   Operation:
  51.  
  52.      A.   Structure of Source Files
  53.  
  54.                ASCII text file listings of macros, which we'll
  55.           refer to as source files from this point onward, must
  56.           conform to an easily achieved structure in order to be
  57.           successfully compiled.  The structure of a source file
  58.           consists of three separate components, as follows:
  59.  
  60.           1)   Header:  all characters from the start of the file
  61.            to the 'STARTMACRO:' code delimiter.
  62.           2)   Code Delimiter:  the word 'STARTMACRO:', including
  63.                its terminating colon.
  64.           3)   Source Code:  all characters from the end of the
  65.                code delimiter to the end of the file.
  66.  
  67.                The compiler will first search through the Header to
  68.           find the phrase,
  69.  
  70.               Macro Description:
  71.  
  72.       All the characters up to a maximum of 39 that occur between
  73.       the colon at the end of the above phrase and the first end of
  74.       line sequence (ASCII 13ASCII 10, produced by pressing your
  75.       [ENTER] key) encountered before the beginning of the
  76.       'STARTMACRO:' code delimiter will be used as the macro
  77.       description.    Thus, if you intend there to be no description
  78.       for the macro, either leave out the 'Macro Description:'
  79.       phrase altogether, or follow it with an immediate press of
  80.       your [ENTER] key.
  81.  
  82.                The compiler then looks for the 'STARTMACRO:' code
  83.           delimiter.  This delimiter MUST appear before the start
  84.           of the source code, or no compilation will occur.  Every
  85.           character after the code delimiter to the end of the
  86.           source file will be compiled into macro code.
  87.  
  88.                To generate an example of how the structure of a
  89.           source file should look, use the Macrolst program to
  90.           create a source file from one of your existing macros. 
  91.           Macrolst creates files which are directly recompilable
  92.           back to macros (i.e., .wpm files).
  93.  
  94.      B.   Syntax of Source Files
  95.  
  96.       1)   All macro and keystroke commands must begin with an
  97.            opening French brace ({) and end with a closing
  98.            French brace (}).
  99.  
  100.       2)   In earlier versions of MacroAde the MCompile program
  101.            required that the case (i.e., upper or lower) of every
  102.            letter between the braces in all macro and keystroke
  103.            commands exactly match that used in the display format
  104.            of the commands.  However, several macro enthusiasts
  105.            have suggested that the goal of any external editing
  106.            capability is ease of use.  To have to observe the
  107.            proper case of command characters conflicts with that
  108.            goal.  Consequently, in this version any mix of cases
  109.            may be used in entering any command.  However, MacroLst
  110.            will continue to translate the commands in a macro in
  111.            accordance with WordPerfect's case format conventions.
  112.            in WordPerfect.
  113.  
  114.       3)   Most of the macro commands are listed and explained in
  115.            detail in Appendix K of the WordPerfect 5.1 manual.
  116.            The complete list of the commands is presentedd for
  117.            syntax reference purposes in the COMMANDS.ref file
  118.            contained in the MacroAde package.
  119.  
  120.       4)   WordPerfect furnishes no list of the keystroke commands
  121.            in the form in which they actually appear in WordPerfect's
  122.            macro editor.  MacroAde provides the needed list of these
  123.            commands in their correct form in its COMMANDS.ref file,
  124.            following the list of macro commands.  Next to each
  125.            keystroke command its WordPerfect code is listed,
  126.            which is needed for some macro commands.  These
  127.            commands must be entered exactly as they appear in
  128.            this list EXCEPT for their case or a syntax error will
  129.            occur and halt compilation.
  130.  
  131.       5)   One special syntax rule that is unique to creating
  132.                source files compilable by MCompile concerns the
  133.                manner in which non-keyboard characters are entered
  134.                to correspond to the use of WordPerfect's 'Compose'
  135.                feature.  This feature is used to access characters
  136.                in WordPerfect character sets above Set 0 (i.e.,
  137.                Sets 1-12), although it can also be used for Set 0
  138.            if there is some reason to do so (e.g., see below for
  139.            the special case of specifying braces as literal
  140.            characters, not parts of commands).  You can specify
  141.                any of these characters in the 13 Character Sets
  142.                (see Appendix P of WordPerfect manual) by entering
  143.            its code using the following syntax:
  144.  
  145.                     [:S,C]
  146.                where:
  147.  
  148.                      S =  the WordPerfect Character Set number (0-
  149.                           12)
  150.                      C =  the number of the character within the
  151.                           specified Character Set
  152.                For example, to specify the copyright symbol, which
  153.                is character 23 in set 4, you could enter:
  154.  
  155.                     [:4,23]
  156.  
  157.            NOTE: Even though the compiler accepts certain high
  158.            ASCII codes in the above form (e.g., [:0,250]) for
  159.            various purposes in the construction of .wpm files,
  160.            do not use any other high ASCII characters (i.e., >126)
  161.            in your macro if they aren't specifically allowed in
  162.            these instructions.  WordPerfect's character set 0 only
  163.            contains the first 126 ASCII characters; use of others
  164.            not authorized here will not be recognized in WordPerfect.
  165.  
  166.       6)   Tabs and spaces may be used at the beginning of
  167.            each line to indent it for formatting purposes.
  168.            The compiler interprets all tab (ASCII 9), and
  169.            space (ASCII 32) characters that occur before any
  170.            other characters at the beginning of a line as
  171.            formatting characters and translates them all to
  172.            tabs.  If you need to continue a line containing a
  173.            sequence of literal spaces (i.e., spaces that actually
  174.            need to be in the macro) in such a manner that would
  175.            cause one of the literal spaces to start the next line,
  176.            represent that first space by ASCII 250 (or [:0,250] if
  177.            your editor won't allow entry of the high ASCII
  178.            characters.)
  179.  
  180.       7)   After the first non-formatting character on each line
  181.            use only tabs, not spaces, to do all spacing for purely
  182.            formatting purposes to make the source code easier to
  183.            read.  The use of spaces for this purpose after the
  184.            first non-formatting character in a line will result
  185.            in the macro actually entering those spaces in the
  186.            document in which the macro is executed.
  187.  
  188.       8)   Ensure that the editor you use to create or modify
  189.                the source file does not replace tabs with spaces
  190.                when its saves the file.  Many editors provide
  191.                configuration options to control this.  For
  192.                example, with QEDIT you must set the configuration
  193.                for tabs (i.e., by executing QCONFIG and selecting
  194.                'Tab Settings' from the menu) to start in Physical
  195.                Tab Expansion Mode and in Tabs Out Mode.  These are
  196.                the first two questions asked in the Tab Setting
  197.                configuration process.  You should also answer 'No'
  198.                to the last question in this part of the
  199.                configuration process--'Do you want to start in
  200.                Smart Tabs Mode?'.
  201.  
  202.       9)   If you want to visibly mark spaces (e.g., for ease
  203.            of counting), use ASCII character 250 (FA Hex) or
  204.            [:0,250] if your editor doesn't allow entry of high
  205.            ASCII characters.  This character will be properly
  206.            compiled as a space character (ASCII 32).
  207.  
  208.      10)   Do NOT use the "{" and "}" characters in any way other
  209.            than to enclose a macro or keystroke command within the
  210.            macro source code.  The compiler assumes that all
  211.            occurrences of these characters are meant to enclose
  212.            commands and will generate an error and terminate
  213.            compilation if they occur without enclosing commands.
  214.            This is the only difference from WordPerfect's internal
  215.            macro editor, which allows you to use these French braces
  216.            as characters having nothing to do with commands.
  217.            You can, however, enter non-command related braces
  218.            in character code form.    Specifically, you can insert
  219.            literal braces anywhere in a macro by using the following
  220.            codes:
  221.                  "{" = [:0,123]
  222.                  "}" = [:0,125]
  223.  
  224.      11)   A violation of any of these syntax rules or the
  225.                occurrence of an illegal or misspelled command will
  226.                cause MCompile to issue an error message and halt
  227.                execution.  It also assigns a value from 11 to 17
  228.                to the DOS Errorlevel variable to designate the
  229.                occurrence of a particular error.  Checking
  230.                Errorlevel is a useful way of checking the
  231.                compilation process when MCompile is executed
  232.                within a batch file.
  233.  
  234.      C.   Once a source file is ready for compiling, the actual
  235.           compilation process is invoked by the following command:
  236.  
  237.               MCompile macro(.lst)
  238.  
  239.       Note that the name of the source file on the MCompile
  240.           command line may exclude the .lst extension, but will
  241.           accept the name with this extension if it is given. 
  242.           MCompile assumes that any source file has the .lst
  243.           extension, but this assumption may be overridden by
  244.           explicitly specifying a different extension.
  245.  
  246.      D.   If for some reason the compilation fails and a macro of
  247.           that name previously existed, the prior version of the
  248.           macro will be preserved.
  249.  
  250. 6.   Technical support:
  251.  
  252.      Free technical support will be furnished to any licensed user
  253.      who calls on weekdays during the hours from 9:00 a.m. to 5:00 p.m.
  254.      (Eastern) at the following number:  (919) 643-3492
  255.  
  256.      We may also be reached by mail at:
  257.  
  258.      Performance Sciences International
  259.      Suite 1250
  260.      3001 Latta Drive
  261.      Summerfield, NC  27358
  262.